Summary

Replaces the JsCommands placeholder in api-specs/openrpc-dapp-api.json with a properly-typed schema. Single commit (5c24ca75), api-specs/openrpc-dapp-api.json only.

This is the upstream candidate for canton-network/wallet-gateway (renamed from hyperledger-labs/splice-wallet-kernel). Opening on the private fork first for structured review before upstreaming.

Why

The components.schemas.JsCommands entry has been a placeholder since #40 ("Api spec placeholders", 2025-06-05):

"JsCommands": {
  "title": "JsCommands",
  "type": "object",
  "description": "Structure representing JS commands for transaction execution",
  "additionalProperties": true
}

Verified still in this state on canton-network/wallet-gateway:main (bd545745).

// =====================================================================
// Pre-fix: the published OpenRPC stub
//   "JsCommands": { "type": "object", "additionalProperties": true }
// → openapi-codeg...

Playground Link

This stub contradicts four other parts of this same repo:

1. Canton Ledger API — api-specs/ledger-api/3.4.12/openapi.yaml (and 3.5.1) define JsCommands.commands as a required, non-empty type: array whose items are $ref: Command.
2. SDK docs — docs/dapp-building/dapp-sdk/usage.md:205 shows { commands: [ { CreateCommand: {...} } ] }.
3. Canonical example — examples/ping/src/commands/createPingCommand.ts:9 builds commands: [ { CreateCommand: {...} } ].
4. Upstream runtime — wallet-gateway/remote/src/dapp-api/controller.ts:243 accesses params.commands?.[0], only valid if commands is an array.

PRs #904, #1259, #1339, and #1609 all touched JsPrepareSubmissionRequest without filling this in.

What changes

• Four named variant schemas (CreateCommand, ExerciseCommand, CreateAndExerciseCommand, ExerciseByKeyCommand), each a one-key tagged object. Inner shapes left opaque (additionalProperties: true) — the description defers to the Canton Ledger API to avoid drift.
• A Command oneOf tagged-union referencing the four variants.
• JsCommands redefined as array of Command, minItems: 1.

The oneOf discriminated-union path is what generated clients need to emit a clean z.union([...]) with openapi-zod-client (the default json-schema-to-zod path produces a superRefine fallback otherwise).

Naming note (not a bug)

The dApp API uses JsCommands as the inner array (array<Command>), with the wrapper object being JsPrepareSubmissionRequest = {commandId, commands: $ref JsCommands, actAs, ...}. The Ledger API uses the same name JsCommands for the outer wrapper {commandId, commands: array<Command>, actAs, ...}. Same logical content, different nesting level. Our patch preserves the existing dApp-API structure (matches JsPrepareSubmissionRequest's pre-existing reference of commands: $ref JsCommands), so this is consistent — not introduced by this PR. Worth verifying in review.

Severity

Blocks CIP-0103 interop for any wallet that generates its JSON-RPC validators from the published OpenRPC spec.

Downstream verification

Verified via Send Canton Wallet webext, with a CIP-0103 conformance Playwright spec driving the upstream examples/ping dApp against a patched wallet.

Base

Rebased onto canton-network/wallet-gateway:main (bd545745). Fork's main synced from old hyperledger-labs/splice-wallet-kernel (62 commits behind canonical) to current canton-network/wallet-gateway tip on 2026-05-08.

Review focus

• Coverage: Are there other Daml command variants in the Ledger API (or planned) that this 4-variant union misses?
• Fidelity: Do our oneOf shapes match what wallet-gateway/remote/src/dapp-api/controller.ts actually accepts at runtime?
• Generation: Verify openapi-zod-client emits clean z.union([z.object({CreateCommand: ...}), ...]) from this oneOf, not a superRefine fallback.
• Naming: Is the JsCommands array-vs-wrapper-object naming inconsistency between dApp API and Ledger API a deliberate layering choice or worth raising upstream?